home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / strlib.zip / README.1ST < prev    next >
Text File  |  1993-01-04  |  8KB  |  141 lines
  1.  
  2. File   : READ-ME
  3. Author : Richard A. O'Keefe.
  4. Updated: 1 June 1984.
  5. Purpose: Explain the new strings package.
  6.  
  7.     The UNIX string libraries (described in the string(3) manual page)
  8. differ from UNIX to UNIX (e.g. strtok is not in V7 or 4.1bsd).  Worse,
  9. the sources are not in the public domain, so that if there is a string
  10. routine which is nearly what you want but not quite you can't  take  a
  11. copy  and  modify it.  And of course C programmers on non-UNIX systems
  12. are at the mercy of their supplier.
  13.  
  14.     This package was designed to let me do reasonable things with  C's
  15. strings  whatever UNIX (V7, PaNiX, UX63, 4.1bsd) I happen to be using.
  16. Everything in the System III manual is here and does just what the  S3
  17. manual  says  it does.  There are also lots of new goodies.  I'm sorry
  18. about the names, but the routines do have to work  on  asphyxiated-at-
  19. birth  systems  which  truncate identifiers.  The convention is that a
  20. routine is called
  21.         str [n] [c] <operation>
  22. If there is an "n", it means that the function takes an (int) "length"
  23. argument, which bounds the number of characters to be moved or  looked
  24. at.  If the function has a "set" argument, a "c" in the name indicates
  25. that  the complement of the set is used.  Functions or variables whose
  26. names start with _ are support routines which aren't really meant  for
  27. general  use.  I don't know what the "p" is doing in "strpbrk", but it
  28. is there in the S3 manual so it's here too.  "istrtok" does not follow
  29. this rule, but with 7 letters what can you do?
  30.  
  31.     I have included new versions of atoi(3) and atol(3) as well.  They
  32. use a new primitive str2int, which takes a pair of bounds and a radix,
  33. and does much more thorough checking than the normal atoi and atol do.
  34. The result returned by atoi & atol is valid if and only if errno == 0.
  35. There is also an output conversion routine int2str, with itoa and ltoa
  36. as interface macros.  Only after writing int2str did I notice that the
  37. str2int routine has no provision for unsigned numbers.  On reflection,
  38. I don't greatly care.   I'm afraid that int2str may depend on your "C"
  39. compiler in unexpected ways.  Do check the code with -S.
  40.  
  41.     Several of these routines have "asm" inclusions conditional on the
  42. VaxAsm option.  These insertions can make the routines which have them
  43. quite a bit faster, but there is a snag.  The VAX architects, for some
  44. reason best known to themselves and their therapists, decided that all
  45. "strings" were shorter than 2^16 bytes.  Even when the length operands
  46. are in 32-bit registers, only 16 bits count.  So the "asm" versions do
  47. not work for long strings.  If you can guarantee that all your strings
  48. will be short, define VaxAsm in the makefile, but in general, and when
  49. using other machines, do not define it.
  50.  
  51.     Thanks to someone on the net who saw the first posting of strings,
  52. and sent me a formatted copy of the System V memory(3C) manual page, I
  53. have been able to include versions of these routines.   The convention
  54. is that they are called
  55.         mem{operation}([dst,] ... , len)
  56. where operation is cpy, cmp, chr, and so on, and len is how many bytes
  57. to move or test.  Note that this is different from the strn functions,
  58.         str{operation}  -- stop when you find a NUL character
  59.         strn{operation} -- stop when len is exhausted or you find NUL
  60.         mem{operation}  -- stop when len is exhausted
  61.         b{operation}    -- stop when len is exhausted
  62. but the b family has different argument orders or different results or
  63. both.  In particular, note that my implementation of bcmp does conform
  64. to the letter of the 4.2bsd manual page, but I decided to make it give
  65. a value I have often wanted, which is not like the value of strcmp. As
  66. the System V manual page is more explicit about the return code memcmp
  67. DOES return a value like strcmp, so you may prefer to use it.  BEWARE:
  68. the "c" in the name mem-c-cpy doesn't mean what it does in the System3
  69. names, it's more like mem-chr-cpy.
  70.  
  71.     To use this library, you need the "strings.a" library file and the
  72. "strings.h" header file.  The other header files are for compiling the
  73. library itself, though if you are hacking extensions you may find them
  74. useful.  General users really shouldn't see them.  I've defined a  few
  75. macros  I find useful in "strings.h"; if you have no need for "index",
  76. "rindex", "streql", and "beql", just edit them  out.   On  the  4.1bsd
  77. system  I  am using, having all these functions 'extern' does not mean
  78. that they will all be loaded; only the ones you call are.  When  using
  79. lesser  systems you may find it necessary to break strings.h up or you
  80. could get by with just adding "extern" declarations for  functions  as
  81. you  need  them.   Note  that  as  many  of these functions have names
  82. matching "standard C library" names (by design, this is  after  all  a
  83. replacement/reimplementation  of part of that library) you may have to
  84. talk the loader into loading this library first.  Again, I've found no
  85. problems on 4.1bsd.
  86.  
  87.     A note on character comparison.  The various UNIX manuals come out
  88. and say explicitly that the *cmp and *chr routines use the computer's
  89. "native" character comparison.  That is, on a PDP-11, VAX-11, and some
  90. other machines, signed character comparison is used, and the byte 0377
  91. will never be located (use -1).   On IBM 370s and many other machines,
  92. unsigned character comparison is used, and the byte -1 can't be found.
  93. (Use 0377.)  If you have occasion to use 8-bit byte values in calls to
  94. *chr functions, it would be nice if the package looked after making it
  95. work portably.  I thought about that, and decided not to do it, as you
  96. might *want* to write VAX code that didn't find 128, and might rely on
  97. the current effect. However, you should be able to use 8-bit values in
  98. a portable fashion if you ask, and that the package DOES do for you.
  99. There is a macro
  100.         int2char(c)
  101. which takes the bottom 8 bits of c on a machine with unsigned character
  102. comparison or sign-extends them on a machine with signed comparison. It
  103. is up to you to use this macro in appropriate places.  It is up to who-
  104. ever installs the package to make sure that the right definition is put
  105. in and the wrong one commented out.
  106.  
  107.     You may wonder at my failure to provide manual pages for this  code.
  108. For  the things in V7, 4.?, or SIII, you should be able to use whichever
  109. manual page came with that system, and anything I might write  would  be
  110. so  like it as to raise suspicions of violating AT&T copyrights.  In the
  111. sources you will find comments which provide far more documentation  for
  112. these  routines  than AT&T ever provided for their strings stuff, I just
  113. don't happen to have put it in nroff -man form.   Had I done so, the *.3
  114. files would have outbulked the .c files!
  115.  
  116.     There is a manual page for the strx family of routines.   It was the
  117. work of Tony Hansen, of AT&T Information Systems Lincroft NJ.  It is not
  118. clear whether I should distribute this manual page or not,  but as these
  119. functions are not likely to documented anywhere else I decided to risk
  120. it.  There is no risk in the *code* however.  His posting to net.sources
  121. arrived at Edinburgh with just the reason for reposting, and the manual
  122. page.  The code is my own work based on his manual page.  Indeed, I had
  123. already written strx[n]mov, using different names.
  124.  
  125.     These files are in the public domain.  This includes getopt.c, which
  126. is the work of Henry Spencer, University of Toronto Zoology, who says of
  127. it "None of this software is derived from Bell software. I had no access
  128. to the source for Bell's versions at the time I wrote it.  This software
  129. is hereby explicitly placed in the public domain.  It may  be  used  for
  130. any purpose on any machine by anyone." I would greatly prefer it if *my*
  131. material received no military use.
  132.  
  133. [This was posted from vax135!ukc!edcaad!edee!edai!ok to the Usenet net.sources
  134. newsgroup on 24-Jun-1984 at 2:13:47 PM.  It is referred to as the second posting
  135. of the library.]
  136.  
  137. [Transferred to CNODE By Jym Dyer and Ted Lemon]
  138.  
  139. [Note:   None of these files have been modofied to work under MS-DOS
  140.      or CP/M, but they should work]
  141.